<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>An overview of Golem &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="Installing Golem" href="install.html" />
    <link rel="prev" title="Welcome to Golem&#8217;s documentation!" href="index.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="install.html" title="Installing Golem"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Welcome to Golem&#8217;s documentation!"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="an-overview-of-golem">
<h1 id="an-overview-of-golem">An overview of Golem<a class="headerlink" href="#an-overview-of-golem" title="Permalink to this headline">¶</a></h1>
<div class="section" id="what-is-golem">
<h2 id="what-is-golem">What is Golem?<a class="headerlink" href="#what-is-golem" title="Permalink to this headline">¶</a></h2>
<p>Golem is a markup language and library for extracting information from many
kinds of CML (<a class="reference external" href="http://cml.sf.net/">Chemical Markup Language</a>) files,
particularly aimed towards processing the output of atomistic simulation
programs.</p>
<p>The Golem markup language annotates CML dictionaries with information about
the types of data associated with dictionary entries, the location of that
data in CML documents, and information on how to parse that data once it has
been found; the Golem library, written in Python, then uses these annotations
to give you a simple, powerful API for extracting and manipulating that data
from collections of CML documents.</p>
<p>In other words, Golem makes it easier to write programs and services that
consume the CML outputted by a range of popular simulation programs - and,
also, the CML within the <a class="reference external" href="http://wwmm.ch.cam.ac.uk/crystaleye/">CrystalEye</a>
database.</p>
</div>
<div class="section" id="who-and-what-uses-golem">
<h2 id="who-and-what-uses-golem">Who (and what) uses Golem?<a class="headerlink" href="#who-and-what-uses-golem" title="Permalink to this headline">¶</a></h2>
<p>A range of tools and systems use Golem to help in the generation of code input
and the processing of code output. For example, the <a class="reference external" href="http://www.materialsgrid.org/">MaterialsGrid</a> system uses Golem to help with generating
both the input files for systems people want to simulate and also in the
generation of the final reports presented to users.</p>
<p>Golem also comes with a range of programs to help with simple data extraction
from CML files, primarily <tt class="docutils literal"><span class="pre">summon</span></tt>, and with the development of
CML dictionaries (<tt class="docutils literal"><span class="pre">make_dictionary</span></tt>).</p>
</div>
<div class="section" id="what-problem-does-golem-solve">
<h2 id="what-problem-does-golem-solve">What problem does Golem solve?<a class="headerlink" href="#what-problem-does-golem-solve" title="Permalink to this headline">¶</a></h2>
<p>Simply that what two codes mean by a given word is usually not identical.
Every code, or resource, which uses CML has a subtly different set of concepts
it is trying to represent. For example, CASTEP and SIESTA have very different
conceptions of their basis sets. As a result, every program uses CML syntax
slightly differently. CML allows for this using its <tt class="docutils literal"><span class="pre">dictRef</span></tt> mechanism:
each concept in a CML document is given a unique name. Golem leverages and
extends this mechanism to allow these differences in usage and document
structure to be encapsulated in Golem/CML Dictionaries, which specify the
concepts and syntax particular to a given domain of CML usage.</p>
<p>A good example is temperature. Consider Monte Carlo and molecular dynamics
simulations; in Monte Carlo, the temperater defines the probability of a
change of configuration, whereas in molecular dynamics it controls the kinetic
energy of the atoms. These are, on one level, the same concept - in the higher
language of thermodynamics, they relate to quantities like the free energy in
the same way - but their usage in the context of the simulations is very
different, even though they legitimately have the same name. Therefore, some
of the time the two conceptualizations of temperatuere will be comparable, and
some of the time they won&#8217;t; any system for processing CML has to be able to
deal with this ambiguity.</p>
</div>
<div class="section" id="codes-and-resources-with-golem-dictionaries">
<h2 id="codes-and-resources-with-golem-dictionaries">Codes and resources with Golem dictionaries<a class="headerlink" href="#codes-and-resources-with-golem-dictionaries" title="Permalink to this headline">¶</a></h2>
<p>Golem comes with dictionaries for:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.castep.org/">CASTEP</a></li>
<li><a class="reference external" href="http://www.esc.cam.ac.uk/ossia/">OSSIA</a></li>
<li>the <a class="reference external" href="http://wwmm.ch.cam.ac.uk/crystaleye/">CrystalEye</a> crystallographic
structure database.</li>
</ul>
<p>If the code you use isn&#8217;t listed here, Golem also includes tools to make it
straightforward to develop new dictionaries for new CML dialects; we have
developed dictionaries for</p>
<ul class="simple">
<li><a class="reference external" href="http://www.cse.scitech.ac.uk/ccg/software/DL_POLY/">DL_POLY</a></li>
<li><a class="reference external" href="http://www.uam.es/siesta/">SIESTA</a></li>
<li><a class="reference external" href="http://www.ivec.org/GULP/">GULP</a></li>
<li><a class="reference external" href="http://www.openmopac.net/">MOPAC</a></li>
<li><a class="reference external" href="http://www.kjemi.uio.no/software/dalton/main.php">DALTON</a></li>
<li><a class="reference external" href="http://www.isis.rl.ac.uk/RMC/rmcprofile.htm">rmcprofile</a></li>
</ul>
<p>using the <tt class="docutils literal"><span class="pre">make_dictionary</span></tt> tool described later in this documentation.
If your code doesn&#8217;t output CML at present, the process of adding markup is
covered later in &#8220;Adding CML markup to your code&#8221;.</p>
</div>
<div class="section" id="how-can-i-get-started">
<h2 id="how-can-i-get-started">How can I get started?<a class="headerlink" href="#how-can-i-get-started" title="Permalink to this headline">¶</a></h2>
<p>The best way to get a feel for Golem is to install it and try it out on some
of your data using <tt class="docutils literal"><span class="pre">summon</span></tt>. In the next chapter, we discuss installing
Golem; the following chapter is an introduction to the <tt class="docutils literal"><span class="pre">summon</span></tt> program,
which enables you to quickly extract, as CSV, the data identified by specific
dictionary entries from one or many CML files.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">An overview of Golem</a><ul>
<li><a class="reference external" href="#what-is-golem">What is Golem?</a></li>
<li><a class="reference external" href="#who-and-what-uses-golem">Who (and what) uses Golem?</a></li>
<li><a class="reference external" href="#what-problem-does-golem-solve">What problem does Golem solve?</a></li>
<li><a class="reference external" href="#codes-and-resources-with-golem-dictionaries">Codes and resources with Golem dictionaries</a></li>
<li><a class="reference external" href="#how-can-i-get-started">How can I get started?</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="index.html" title="previous chapter">Welcome to Golem&#8217;s documentation!</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="install.html" title="next chapter">Installing Golem</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/overview.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="install.html" title="Installing Golem"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Welcome to Golem&#8217;s documentation!"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>